document: Web Calls Service API

group: Introduction

The Web Calls Service is used by webAppOS and some apps
to invoke web calls.

group: Access URL

The Web Calls Service is accessible via the following URL:
---code---
GET/POST http[s]://[domain_or_ip]/services/webcalls/[action-name]
GET/POST http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]
GET/POST http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]
----------

group: Authentication

Public web calls actions do not require
authentication. 

Non-public calls require the "login" and "ws_token" arguments in the query string.

Non-static calls also require the "project_id" argument.

Besides, the "app_url_name" parameter can be specified to inform webAppOS and the web call
about which web app is making the call. Although, webAppOS will try to infer the web app from
other known information (e.g., from the web call location), providing the "app_url_name" explicitly
can ensure that webAppOS knows about the web app even when an error occurs.

Example:

---code---
GET/POST https://example.org/services/webcalls/someAction?login=user1&ws_token=123456&project_id=user1/myproject.owlgred
----------

group: Sending an argument via the GET method

Since the GET method does not have the data body, the web call argument must be encoded
in the query string.

For jsoncall calling conventions, there are 2 options:

* to pass a string as a query argument named "argument";
* to encode the JSON argument as an URL data string
  and pass it as the query argument named "json_argument";
* or to encode each property of the JSON as a separate query argument in the name=value format, delimited by &.

Examples:

---code---
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&argument=[some-string-to-be-passed-as-argument]
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&json_argument=[stringified-JSON-argument]
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&[property1]=[value1]&[property2]=[value2]&...
----------

For webmemcall calling conventions, specify the argument (object reference) via the argument
query parameter:

Example:

---code---
GET http[s]://[domain_or_ip]/services/webcalls/[action-name]?login=[login]&ws_token=[ws_token]&project_id=[project_id]&argument=[reference]
----------

group: Sending an argument via the POST method

Data must be sent as POST data encoded in UTF-8.

The following content types are supported:
---code---
Content-Type: application/json
Content-Type: multipart/form-data
Content-Type: application/x-www-form-urlencoded
----------

In the latter two cases, the name=value pairs are assumed as properties { name: value } of the JSON object
that will be passed to the web call.

group: Web call result

Normally, the web call result is a JSON data (application/json).
If an error occurred, a JSON object with the "error" property is returned.

group: Pipe-like usage of the web call result

The web call result can be piped (injected) into HTML files. This is useful when
JavaScript is not available, but the desired HTML file contains placeholders, which
should be filled with some variable data returned by the web call.

The placeholder must be an HTML comment containing some JSON property name, e.g.:

---code---
<!--name-->
----------

Then, if the web call returns a JSON { name: "John" }, the "<!--name-->" placeholder will be replaced by "John".

HTML files can be specified by appending to the query string one of the following:
---code---
|[on-success-HTML]
|[on-success-HTML],[on-error-HTML]
^[on-success-HTML]
^[on-success-HTML],[on-error-HTML]
----------

If only [on-success-HTML] is specified, all JSON properties are injected there. Otherwise,
either the [on-success-HTML], or the [on-error-HTML] is used 
depending on whether the returned JSON contains the "error" property.

Both [on-success-HTML] and [on-error-HTML] are just names of .html files located
in the web-root directory of the corresponding web app.

If "|" is used, the content of the HTML with injected JSON properties is returned as a response.

If "^" is used, a redirect to some HTML with injected JSON properties is returned. Use
"^" to avoid multiple web calls, when the user refreshed the page containing the resulting HTML.
This is in accordance with the Post-Redirect-Get principle (however, "^" works not only
for the initial POST, but also GET requests).

Example:

---code---
?some=URL&query=string|user_registered,user_not_registered
----------


It is recommended to add the "app_url_name" argument to the query string (but before the "|" or "^" symbols),
so that webAppOS could find the corresponding on-success/on-error HTML files even when an error occurs.

Example:

---code---
?some=URL&query=string&app_url_name=myapp|user_registered,user_not_registered
----------
